Quarto

Universitat Oberta de Catalunya

Jordi Mas Elias

https://www.jordimas.cat/

Sumari

  1. Què és Quarto?
  2. Repàs primeres sessions
  3. Tutorial RMarkdown
  4. RMarkdown avançat
  5. Consideracions finals

1. Què és Quarto?

Orígens: Markdown

“A Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions”

Illustration of three species of Palmer Archipelago penguins: Chinstrap, Gentoo, and Adelie. Artwork by @allison_horst.

  • John Gruber, 2004.
  • Un format més fàcil de llegir i d’escriure que la majoria de llenguatges web com l’Html.
  • Convertible fàcilment a Html, Pdf…

Orígens: RMarkdown

  • S’adopta a RStudio.
  • Permet alternar codi d’R amb text.
  • Fàcilment exportable a varis formats
  • Exemples:

Orígens: RMarkdown

Crear un document: YAML - Text - Chunk

RMarkdown logo.

Orígens: Quarto

Quarto

Posit

2. Elements principals de Quarto

YAML

  • Què és?
  • Nom, títol i data.
  • ---

Exercici 1: YAML

Provar amb:

output:
  html_document:
    theme: cosmo

Text

  • Negreta, cursives, codi, enllaços, nota al peu1.

  • Seccions i subseccions

  • Ítems i subítems.

  • Ítems enumerats.

Exercici 2: Text

Llegir introducció i fins a la imatge de RMarkdown. Fer els canvis que es proposen en el text.

Chunks

  • Què és? Ctrl + Alt + I
  • Inici i final d’un chunk.
  • Etiquetes del chunk.
  • Elements: echo, eval, message, warning.

Exercici 3: Chunks

Llegir l’apartat chunks i fer canvis que es proposen.

Taules, imatges i gràfics

  • Els posem a dins del chunk.
  • Marc de dades: tibble, kable, datatable.
  • Imatges: ![]() o include_graphics("__").
  • Gràfics: fig.align = "center", fig.width = 50%.

Exercici 4: Dades i gràfics

Llegir l’últim apartat, modifica marc de dades i gràfic.

Avís important

És important diferenciar entre

  • Mode Knit
  • Mode R Script

Activitat

Exercici 5: Polity V

Crear una petita història amb Polity V:

  • Descarregar la base de dades Polity V a Systemic Peace
  • Text amb tots els formats possibles.
  • Un marc de dades i dos plots.

4. RMarkdown avançat I

4.1. RMarkdown avançat (YAML)

Data automàtica

Quan fem Knit, ens imprimeix automàticament el dia d’avui.

date: "`r Sys.Date()`"
[1] "2023-02-28"
date: "`r format(Sys.time(), '%d %B %Y')`"
[1] "28 February 2023"
date: "Última edició `r format(Sys.time(), '%d %B %Y')`"
[1] "Última edició 28 February 2023"

Foto d’encapçalament

Posem una foto a la capçalera del document.

title: "![Posar nom de títol](polity-index.jpeg){width=2in}"

Taula de continguts

Customitzem elements de la taula de continguts.

output:
  html_document:
    toc: true
    toc_depth: 2
    number_sections: true
    toc_float:
      collapsed: false
        smooth_scroll: false

Temes

Seleccionem l’estil visual i el subratllat:

  • Tema: default, cerulean, journal, flatly, darkly, readable, spacelab, united, cosmo, lumen, paper, sandstone, simplex, yeti, null.
theme: paper
  • Highlight: default, tango, pygments, kate, monochrome, espresso, zenburn, haddock, breezedark, textmate, null.
highlight: tango

Plegar codi

Creem un desplegable per cada chunk amb codi (echo = T) que tinguem al document.

title: "Postgrau d'Analista de Dades (UB)"
output:
  html_document:
    code_folding: hide

Formats d’output

Al YAML podem especificar el tipus de format1.

title: "Postgrau d'Analista de Dades (UB)"
author: "Nom de l'estudiant"
output:
  html_document:
    code_folding: hide
  pdf_document:
    toc: yes
  word_document:

I també podem crear diapositives en diversos formats.

4.2. RMarkdown avançat (text)

Canviar mida de text

Un dels deutes pendents de RMarkdown.

    <style>
    body {
    font-size: 13pt;
    text-align: justify}
    </style>

Incloure codi al text

En qualsevol moment podem fer referència al text sobre qualsevol dada ja carregada en un chunk previ.

  • A. Carreguem les dades:
polity <- read_excel("data/p5v2018.xls")
  • B. Referenciem les dades al text:

En aquest gràfic veiem Estats Units en els darrers anys

p5_ctr <- polity |> 
  filter(country == params$country, year > params$year) |> 
  select(country, year, polity2)
knitr::kable(p5_ctr)
country year polity2
United States 2013 10
United States 2014 10
United States 2015 10
United States 2016 8
United States 2017 8
United States 2018 8

Observem que en l’últim any de dades 2018, United States tenia un nivell de democràcia de 8.

  • r last(p5_dk$year)
  • r params$country
  • r last(p5_dk$polity2)
polity |> 
  group_by(country) |> 
  summarize(duration = max(durable, na.rm = T)) |> 
  ggplot(aes(x = duration)) +
  geom_density()

El règim amb més durada és United States amb 209 anys:

polity$country[which(polity$durable == max(polity$durable, na.rm = T))]

max(polity$durable, na.rm = T)

Referències al text

Per referenciar la secció del document1:

# Introducció {#intro}

En qualsevol moment del text, introduïm:

[text](#intro)

Referències bibliogràfiques

Ho farem normalment amb un document BibTex (.bib)1.

  1. Obrim un Text file, el guardem com a biblio.bib i introduïm:
@misc{Marshall2020,
author = {Marshall, Monty G. and Gurr, Ted Robert},
publisher = {Center for Systemic Peace},
title = {{Polity V. Political Regime Characteristics and Transitions, 1800-2018}},
year = {2020}
}
  1. Indiquem al YAML on es troba l’arxiu:
bibliography: biblio.bib
  1. Citem les referències al text.
  • Entre claudàtors [@Marshall2020], ens posarà (Marshall 2020).
  • Sense claudàtors @Marshall2020, ens posarà Marshall (2020).
  1. En l’última línia del document de RMarkdown, posarem un títol # Referències per separar la bibliografia de la resta del text.

4.3. RMarkdown avançat (chunks)

Taules

Tot tipus de taules amb el paquet KableExtra

polity |> 
  filter(country %in% c("Angola", "Spain", "Vietnam"),
         year == 2014) |> 
  select(country, scode, polity2, durable) |> 
  knitr::kable()

Arguments d’interès:

polity |> 
  select(country, scode, polity2, durable) |> 
  DT::datatable()

Figures

Varis paràmetres per establir les dimensions:

  • fig.width: amplada en inches.
  • fig.height: alçada en inches.
  • fig.align: “left”, “right”, “center”.
  • fig.dim: primer width i després height, c(5,3)
  • out.width: “50%” ocuparà el 50% de l’amplada del report

Opcions globals

Opcions per defecte als chunks de tot el document:

knitr::opts_chunk$set(fig.align = "center", echo = TRUE,
                      warning = FALSE, message = FALSE,
                       fig.width = 6, fig.height = 6)

El primer chunk també és útil per carregar els paquets i objectes que necessitarem.

Què evitar als chunks

  • La funció install.packages().
  • La funció download.file().
  • La funció View().
  • Carregar bases de dades d’internet.
  • Funcions que carreguen bases de dades (ex. CEOdata)

4.4. RMarkdown avançat (publicar)

Exportar i publicar

Tres maneres de publicar en Html:

Activitat

Exercici 7: Prova final

Agafeu el treball d’un dataset anterior i construiu un document Html, procurant d’utilitzar també algunes de les funcions avançades. En particular:

  • Marc de dades en knitr o DT.
  • Temes i subratllats.
  • Plegar codi.
  • Mida gràfics.

Publiqueu-ho a RPubs: A dins d’RStudio, un cop l’Html s’hagi generat en el Viewer, cliqueu a l’icona blava del Viewer (Publish -> Publish a Document), seleccioneu RPubs i seguiu les instruccions.

5. RMarkdown avançat II

5.1. RMarkdown avançat (YAML)

Gràfics per defecte

Els gràfics que apareixen al document han de tenir per defecte algunes dimensions determinades?

title: "Postgrau d'Analista de Dades (UB)"
output:
  html_document:
    fig_width: 6 
    fig_height: 4

Paràmetres

Establim uns paràmetres al YAML que al llarg del document podrem utilitzar com a codi 1.

title: "Postgrau d'Analista de Dades (UB)"
author: "Jordi Mas Elias"
params:
  country: "United States"
  year: 2014

5.2. RMarkdown avançat (text)

Tabsets

## Títol {.tabset}

Aquí comença una tabset.

### Tab A

Contingut de `Tab A`

### Tab B

Contingut de `Tab B`

## {-}

Taules

També una assignatura pendent de RMarkdown.

    | Funció       | Paquet    | Descripció                                           |
    |--------------|-----------|------------------------------------------------------|
    | `filter()`   | `dplyr`   | Filtra les observacions d'un marc de dades           |
    | `separate()` | `tidyr`   | Separa els elements d'un vector en base a un criteri |
    | `read_csv()` | `readr`   | Llegeix els arxius CSV                               |
    | `ggplot()`   | `ggplot2` | Reprodueix elements gràfics                          |
Funció Paquet Descripció
filter() dplyr Filtra les observacions d’un marc de dades
separate() tidyr Separa els elements d’un vector en base a un criteri
read_csv() readr Llegeix els arxius CSV
ggplot() ggplot2 Reprodueix elements gràfics

També podem utilitzar l’Editor Visual (següent).

Editor visual

Interfície més semblant a Word per generar documents.

Amb l’editor visual veurem una interfície que ens serà molt més familiar. No obstant, recomanem utilitzar-lo només puntualment.

Quadres de text

Avís!

Utilitzar quadres de text és una manera efectiva per dirigir l’atenció a determinat contingut.

<div class="alert alert-info">
**Informació!** Blablabla.
</div>

Tipus:

  • primary, secondary, success, danger, warning, info, light, dark.

5.3. RMarkdown avançat (chunk)

Incrustar vídeos i tuits

Amb el paquet vembedr és molt fàcil.

embed_url("https://youtu.be/hz3J6Wb5S_8")

Encara més fàcil amb altres formats de Bookdown:

{{< video https://youtu.be/wo9vZccmqwc >}}
{{< tweet 1229386394658836480 >}}

6. Consideracions finals

Interactius

leaflet() %>% 
  addProviderTiles(providers$Stamen.Toner) %>%
    setView(lng = 139.753930, 
          lat = 35.682170, 
          zoom = 13)

Bibliografia principal

Quarto - UOC